<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Porting to Python 3 &mdash; Django 1.7.8.dev20150401230226 documentation</title>
    
    <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.7.8.dev20150401230226',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="top" title="Django 1.7.8.dev20150401230226 documentation" href="../index.html" />
    <link rel="up" title="Using Django" href="index.html" />
    <link rel="next" title="Security in Django" href="security.html" />
    <link rel="prev" title="Pagination" href="pagination.html" />



 
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);
</script>


  </head>
  <body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../index.html">Django 1.7.8.dev20150401230226 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../index.html">Home</a>  |
        <a title="Table of contents" href="../contents.html">Table of contents</a>  |
        <a title="Global index" href="../genindex.html">Index</a>  |
        <a title="Module index" href="../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="pagination.html" title="Pagination">previous</a>
     |
    <a href="index.html" title="Using Django" accesskey="U">up</a>
   |
    <a href="security.html" title="Security in Django">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="topics-python3">
            
  <div class="section" id="s-porting-to-python-3">
<span id="porting-to-python-3"></span><h1>Porting to Python 3<a class="headerlink" href="#porting-to-python-3" title="Permalink to this headline">¶</a></h1>
<p>Django 1.5 is the first version of Django to support Python 3. The same code
runs both on Python 2 (≥&nbsp;2.6.5) and Python 3 (≥&nbsp;3.2), thanks to the <a class="reference external" href="http://pythonhosted.org/six/">six</a>
compatibility layer.</p>
<p>This document is primarily targeted at authors of pluggable application
who want to support both Python 2 and 3. It also describes guidelines that
apply to Django&#8217;s code.</p>
<div class="section" id="s-philosophy">
<span id="philosophy"></span><h2>Philosophy<a class="headerlink" href="#philosophy" title="Permalink to this headline">¶</a></h2>
<p>This document assumes that you are familiar with the changes between Python 2
and Python 3. If you aren&#8217;t, read <a class="reference external" href="http://docs.python.org/3/howto/pyporting.html">Python&#8217;s official porting guide</a> first.
Refreshing your knowledge of unicode handling on Python 2 and 3 will help; the
<a class="reference external" href="http://nedbatchelder.com/text/unipain.html">Pragmatic Unicode</a> presentation is a good resource.</p>
<p>Django uses the <em>Python 2/3 Compatible Source</em> strategy. Of course, you&#8217;re
free to chose another strategy for your own code, especially if you don&#8217;t need
to stay compatible with Python 2. But authors of pluggable applications are
encouraged to use the same porting strategy as Django itself.</p>
<p>Writing compatible code is much easier if you target Python ≥ 2.6. Django 1.5
introduces compatibility tools such as <a class="reference internal" href="#module-django.utils.six" title="django.utils.six"><tt class="xref py py-mod docutils literal"><span class="pre">django.utils.six</span></tt></a>, which is a
customized version of the <a class="reference external" href="http://pythonhosted.org/six/index.html#module-six" title="(in six v1.9)"><tt class="xref py py-mod docutils literal"><span class="pre">six</span> <span class="pre">module</span></tt></a>. For convenience,
forwards-compatible aliases were introduced in Django 1.4.2. If your
application takes advantage of these tools, it will require Django ≥ 1.4.2.</p>
<p>Obviously, writing compatible source code adds some overhead, and that can
cause frustration. Django&#8217;s developers have found that attempting to write
Python 3 code that&#8217;s compatible with Python 2 is much more rewarding than the
opposite. Not only does that make your code more future-proof, but Python 3&#8217;s
advantages (like the saner string handling) start shining quickly. Dealing
with Python 2 becomes a backwards compatibility requirement, and we as
developers are used to dealing with such constraints.</p>
<p>Porting tools provided by Django are inspired by this philosophy, and it&#8217;s
reflected throughout this guide.</p>
</div>
<div class="section" id="s-porting-tips">
<span id="porting-tips"></span><h2>Porting tips<a class="headerlink" href="#porting-tips" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-unicode-literals">
<span id="unicode-literals"></span><h3>Unicode literals<a class="headerlink" href="#unicode-literals" title="Permalink to this headline">¶</a></h3>
<p>This step consists in:</p>
<ul class="simple">
<li>Adding <tt class="docutils literal"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span> <span class="pre">unicode_literals</span></tt> at the top of your Python
modules &#8211; it&#8217;s best to put it in each and every module, otherwise you&#8217;ll
keep checking the top of your files to see which mode is in effect;</li>
<li>Removing the <tt class="docutils literal"><span class="pre">u</span></tt> prefix before unicode strings;</li>
<li>Adding a <tt class="docutils literal"><span class="pre">b</span></tt> prefix before bytestrings.</li>
</ul>
<p>Performing these changes systematically guarantees backwards compatibility.</p>
<p>However, Django applications generally don&#8217;t need bytestrings, since Django
only exposes unicode interfaces to the programmer. Python 3 discourages using
bytestrings, except for binary data or byte-oriented interfaces. Python 2
makes bytestrings and unicode strings effectively interchangeable, as long as
they only contain ASCII data. Take advantage of this to use unicode strings
wherever possible and avoid the <tt class="docutils literal"><span class="pre">b</span></tt> prefixes.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Python 2&#8217;s <tt class="docutils literal"><span class="pre">u</span></tt> prefix is a syntax error in Python 3.2 but it will be
allowed again in Python 3.3 thanks to <span class="target" id="index-0"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0414"><strong>PEP 414</strong></a>. Thus, this
transformation is optional if you target Python ≥ 3.3. It&#8217;s still
recommended, per the &#8220;write Python 3 code&#8221; philosophy.</p>
</div>
</div>
<div class="section" id="s-string-handling">
<span id="string-handling"></span><h3>String handling<a class="headerlink" href="#string-handling" title="Permalink to this headline">¶</a></h3>
<p>Python 2&#8217;s <a class="reference external" href="http://docs.python.org/2/library/functions.html#unicode">unicode</a> type was renamed <a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.4)"><tt class="xref py py-class docutils literal"><span class="pre">str</span></tt></a> in Python 3,
<tt class="docutils literal"><span class="pre">str()</span></tt> was renamed <a class="reference external" href="http://docs.python.org/3/library/functions.html#bytes" title="(in Python v3.4)"><tt class="xref py py-class docutils literal"><span class="pre">bytes</span></tt></a>, and <a class="reference external" href="http://docs.python.org/2/library/functions.html#basestring">basestring</a> disappeared.
<a class="reference external" href="http://pythonhosted.org/six/">six</a> provides <a class="reference internal" href="#string-handling-with-six"><em>tools</em></a> to deal with these
changes.</p>
<p>Django also contains several string related classes and functions in the
<a class="reference internal" href="../ref/utils.html#module-django.utils.encoding" title="django.utils.encoding: A series of helper functions to manage character encoding."><tt class="xref py py-mod docutils literal"><span class="pre">django.utils.encoding</span></tt></a> and <a class="reference internal" href="../ref/utils.html#module-django.utils.safestring" title="django.utils.safestring: Functions and classes for working with strings that can be displayed safely without further escaping in HTML."><tt class="xref py py-mod docutils literal"><span class="pre">django.utils.safestring</span></tt></a> modules. Their
names used the words <tt class="docutils literal"><span class="pre">str</span></tt>, which doesn&#8217;t mean the same thing in Python 2
and Python 3, and <tt class="docutils literal"><span class="pre">unicode</span></tt>, which doesn&#8217;t exist in Python 3. In order to
avoid ambiguity and confusion these concepts were renamed <tt class="docutils literal"><span class="pre">bytes</span></tt> and
<tt class="docutils literal"><span class="pre">text</span></tt>.</p>
<p>Here are the name changes in <a class="reference internal" href="../ref/utils.html#module-django.utils.encoding" title="django.utils.encoding: A series of helper functions to manage character encoding."><tt class="xref py py-mod docutils literal"><span class="pre">django.utils.encoding</span></tt></a>:</p>
<table class="docutils">
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Old name</th>
<th class="head">New name</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">smart_str</span></tt></td>
<td><tt class="docutils literal"><span class="pre">smart_bytes</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">smart_unicode</span></tt></td>
<td><tt class="docutils literal"><span class="pre">smart_text</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">force_unicode</span></tt></td>
<td><tt class="docutils literal"><span class="pre">force_text</span></tt></td>
</tr>
</tbody>
</table>
<p>For backwards compatibility, the old names still work on Python 2. Under
Python 3, <tt class="docutils literal"><span class="pre">smart_str</span></tt> is an alias for <tt class="docutils literal"><span class="pre">smart_text</span></tt>.</p>
<p>For forwards compatibility, the new names work as of Django 1.4.2.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="../ref/utils.html#module-django.utils.encoding" title="django.utils.encoding: A series of helper functions to manage character encoding."><tt class="xref py py-mod docutils literal"><span class="pre">django.utils.encoding</span></tt></a> was deeply refactored in Django 1.5 to
provide a more consistent API. Check its documentation for more
information.</p>
</div>
<p><a class="reference internal" href="../ref/utils.html#module-django.utils.safestring" title="django.utils.safestring: Functions and classes for working with strings that can be displayed safely without further escaping in HTML."><tt class="xref py py-mod docutils literal"><span class="pre">django.utils.safestring</span></tt></a> is mostly used via the
<a class="reference internal" href="../ref/utils.html#django.utils.safestring.mark_safe" title="django.utils.safestring.mark_safe"><tt class="xref py py-func docutils literal"><span class="pre">mark_safe()</span></tt></a> and
<a class="reference internal" href="../ref/utils.html#django.utils.safestring.mark_for_escaping" title="django.utils.safestring.mark_for_escaping"><tt class="xref py py-func docutils literal"><span class="pre">mark_for_escaping()</span></tt></a> functions, which didn&#8217;t
change. In case you&#8217;re using the internals, here are the name changes:</p>
<table class="docutils">
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Old name</th>
<th class="head">New name</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">EscapeString</span></tt></td>
<td><tt class="docutils literal"><span class="pre">EscapeBytes</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">EscapeUnicode</span></tt></td>
<td><tt class="docutils literal"><span class="pre">EscapeText</span></tt></td>
</tr>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">SafeString</span></tt></td>
<td><tt class="docutils literal"><span class="pre">SafeBytes</span></tt></td>
</tr>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">SafeUnicode</span></tt></td>
<td><tt class="docutils literal"><span class="pre">SafeText</span></tt></td>
</tr>
</tbody>
</table>
<p>For backwards compatibility, the old names still work on Python 2. Under
Python 3, <tt class="docutils literal"><span class="pre">EscapeString</span></tt> and <tt class="docutils literal"><span class="pre">SafeString</span></tt> are aliases for <tt class="docutils literal"><span class="pre">EscapeText</span></tt>
and <tt class="docutils literal"><span class="pre">SafeText</span></tt> respectively.</p>
<p>For forwards compatibility, the new names work as of Django 1.4.2.</p>
</div>
<div class="section" id="s-str-and-unicode-methods">
<span id="str-and-unicode-methods"></span><h3><a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__str__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__str__()</span></tt></a> and <a class="reference external" href="https://docs.python.org/2/reference/datamodel.html#object.__unicode__">&nbsp;__unicode__()</a> methods<a class="headerlink" href="#str-and-unicode-methods" title="Permalink to this headline">¶</a></h3>
<p>In Python 2, the object model specifies <a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__str__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__str__()</span></tt></a> and
<a class="reference external" href="https://docs.python.org/2/reference/datamodel.html#object.__unicode__">&nbsp;__unicode__()</a> methods. If these methods exist, they must return
<tt class="docutils literal"><span class="pre">str</span></tt> (bytes) and <tt class="docutils literal"><span class="pre">unicode</span></tt> (text) respectively.</p>
<p>The <tt class="docutils literal"><span class="pre">print</span></tt> statement and the <a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.4)"><tt class="xref py py-class docutils literal"><span class="pre">str</span></tt></a> built-in call
<a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__str__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__str__()</span></tt></a> to determine the human-readable representation of an
object. The <tt class="docutils literal"><span class="pre">unicode</span></tt> built-in calls <a class="reference external" href="https://docs.python.org/2/reference/datamodel.html#object.__unicode__">&nbsp;__unicode__()</a> if it
exists, and otherwise falls back to <a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__str__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__str__()</span></tt></a> and decodes the
result with the system encoding. Conversely, the
<a class="reference internal" href="../ref/models/instances.html#django.db.models.Model" title="django.db.models.Model"><tt class="xref py py-class docutils literal"><span class="pre">Model</span></tt></a> base class automatically derives
<a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__str__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__str__()</span></tt></a> from <a class="reference external" href="https://docs.python.org/2/reference/datamodel.html#object.__unicode__">&nbsp;__unicode__()</a> by encoding to UTF-8.</p>
<p>In Python 3, there&#8217;s simply <a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__str__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__str__()</span></tt></a>, which must return <tt class="docutils literal"><span class="pre">str</span></tt>
(text).</p>
<p>(It is also possible to define <a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__bytes__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__bytes__()</span></tt></a>, but Django application
have little use for that method, because they hardly ever deal with <tt class="docutils literal"><span class="pre">bytes</span></tt>.)</p>
<p>Django provides a simple way to define <a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__str__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__str__()</span></tt></a> and
<a class="reference external" href="https://docs.python.org/2/reference/datamodel.html#object.__unicode__">&nbsp;__unicode__()</a> methods that work on Python 2 and 3: you must
define a <a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__str__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__str__()</span></tt></a> method returning text and to apply the
<a class="reference internal" href="../ref/utils.html#django.utils.encoding.python_2_unicode_compatible" title="django.utils.encoding.python_2_unicode_compatible"><tt class="xref py py-func docutils literal"><span class="pre">python_2_unicode_compatible()</span></tt></a> decorator.</p>
<p>On Python 3, the decorator is a no-op. On Python 2, it defines appropriate
<a class="reference external" href="https://docs.python.org/2/reference/datamodel.html#object.__unicode__">&nbsp;__unicode__()</a> and <a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__str__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__str__()</span></tt></a> methods (replacing the
original <a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__str__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__str__()</span></tt></a> method in the process). Here&#8217;s an example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">unicode_literals</span>
<span class="kn">from</span> <span class="nn">django.utils.encoding</span> <span class="kn">import</span> <span class="n">python_2_unicode_compatible</span>

<span class="nd">@python_2_unicode_compatible</span>
<span class="k">class</span> <span class="nc">MyClass</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">&quot;Instance of my class&quot;</span>
</pre></div>
</div>
<p>This technique is the best match for Django&#8217;s porting philosophy.</p>
<p>For forwards compatibility, this decorator is available as of Django 1.4.2.</p>
<p>Finally, note that <a class="reference external" href="http://docs.python.org/3/reference/datamodel.html#object.__repr__" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">__repr__()</span></tt></a> must return a <tt class="docutils literal"><span class="pre">str</span></tt> on all
versions of Python.</p>
</div>
<div class="section" id="s-dict-and-dict-like-classes">
<span id="dict-and-dict-like-classes"></span><h3><a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.4)"><tt class="xref py py-class docutils literal"><span class="pre">dict</span></tt></a> and <a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.4)"><tt class="xref py py-class docutils literal"><span class="pre">dict</span></tt></a>-like classes<a class="headerlink" href="#dict-and-dict-like-classes" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#dict.keys" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">dict.keys()</span></tt></a>, <a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#dict.items" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">dict.items()</span></tt></a> and <a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#dict.values" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">dict.values()</span></tt></a> return lists in
Python 2 and iterators in Python 3. <a class="reference internal" href="../ref/request-response.html#django.http.QueryDict" title="django.http.QueryDict"><tt class="xref py py-class docutils literal"><span class="pre">QueryDict</span></tt></a> and the
<a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.4)"><tt class="xref py py-class docutils literal"><span class="pre">dict</span></tt></a>-like classes defined in <a class="reference internal" href="../ref/utils.html#module-django.utils.datastructures" title="django.utils.datastructures: Data structures that aren't in Python's standard library."><tt class="xref py py-mod docutils literal"><span class="pre">django.utils.datastructures</span></tt></a>
behave likewise in Python 3.</p>
<p><a class="reference external" href="http://pythonhosted.org/six/">six</a> provides compatibility functions to work around this change:
<a class="reference external" href="http://pythonhosted.org/six/index.html#six.iterkeys" title="(in six v1.9)"><tt class="xref py py-func docutils literal"><span class="pre">iterkeys()</span></tt></a>, <a class="reference external" href="http://pythonhosted.org/six/index.html#six.iteritems" title="(in six v1.9)"><tt class="xref py py-func docutils literal"><span class="pre">iteritems()</span></tt></a>, and <a class="reference external" href="http://pythonhosted.org/six/index.html#six.itervalues" title="(in six v1.9)"><tt class="xref py py-func docutils literal"><span class="pre">itervalues()</span></tt></a>.
It also contains an undocumented <tt class="docutils literal"><span class="pre">iterlists</span></tt> function that works well for
<tt class="docutils literal"><span class="pre">django.utils.datastructures.MultiValueDict</span></tt> and its subclasses.</p>
</div>
<div class="section" id="s-httprequest-and-httpresponse-objects">
<span id="httprequest-and-httpresponse-objects"></span><h3><a class="reference internal" href="../ref/request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><tt class="xref py py-class docutils literal"><span class="pre">HttpRequest</span></tt></a> and <a class="reference internal" href="../ref/request-response.html#django.http.HttpResponse" title="django.http.HttpResponse"><tt class="xref py py-class docutils literal"><span class="pre">HttpResponse</span></tt></a> objects<a class="headerlink" href="#httprequest-and-httpresponse-objects" title="Permalink to this headline">¶</a></h3>
<p>According to <span class="target" id="index-1"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-3333"><strong>PEP 3333</strong></a>:</p>
<ul class="simple">
<li>headers are always <tt class="docutils literal"><span class="pre">str</span></tt> objects,</li>
<li>input and output streams are always <tt class="docutils literal"><span class="pre">bytes</span></tt> objects.</li>
</ul>
<p>Specifically, <a class="reference internal" href="../ref/request-response.html#django.http.HttpResponse.content" title="django.http.HttpResponse.content"><tt class="xref py py-attr docutils literal"><span class="pre">HttpResponse.content</span></tt></a>
contains <tt class="docutils literal"><span class="pre">bytes</span></tt>, which may become an issue if you compare it with a
<tt class="docutils literal"><span class="pre">str</span></tt> in your tests. The preferred solution is to rely on
<a class="reference internal" href="testing/tools.html#django.test.SimpleTestCase.assertContains" title="django.test.SimpleTestCase.assertContains"><tt class="xref py py-meth docutils literal"><span class="pre">assertContains()</span></tt></a> and
<a class="reference internal" href="testing/tools.html#django.test.SimpleTestCase.assertNotContains" title="django.test.SimpleTestCase.assertNotContains"><tt class="xref py py-meth docutils literal"><span class="pre">assertNotContains()</span></tt></a>. These methods accept a
response and a unicode string as arguments.</p>
</div>
</div>
<div class="section" id="s-coding-guidelines">
<span id="coding-guidelines"></span><h2>Coding guidelines<a class="headerlink" href="#coding-guidelines" title="Permalink to this headline">¶</a></h2>
<p>The following guidelines are enforced in Django&#8217;s source code. They&#8217;re also
recommended for third-party application who follow the same porting strategy.</p>
<div class="section" id="s-syntax-requirements">
<span id="syntax-requirements"></span><h3>Syntax requirements<a class="headerlink" href="#syntax-requirements" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-unicode">
<span id="unicode"></span><h4>Unicode<a class="headerlink" href="#unicode" title="Permalink to this headline">¶</a></h4>
<p>In Python 3, all strings are considered Unicode by default. The <tt class="docutils literal"><span class="pre">unicode</span></tt>
type from Python 2 is called <tt class="docutils literal"><span class="pre">str</span></tt> in Python 3, and <tt class="docutils literal"><span class="pre">str</span></tt> becomes
<tt class="docutils literal"><span class="pre">bytes</span></tt>.</p>
<p>You mustn&#8217;t use the <tt class="docutils literal"><span class="pre">u</span></tt> prefix before a unicode string literal because it&#8217;s
a syntax error in Python 3.2. You must prefix byte strings with <tt class="docutils literal"><span class="pre">b</span></tt>.</p>
<p>In order to enable the same behavior in Python 2, every module must import
<tt class="docutils literal"><span class="pre">unicode_literals</span></tt> from <tt class="docutils literal"><span class="pre">__future__</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">unicode_literals</span>

<span class="n">my_string</span> <span class="o">=</span> <span class="s">&quot;This is an unicode literal&quot;</span>
<span class="n">my_bytestring</span> <span class="o">=</span> <span class="n">b</span><span class="s">&quot;This is a bytestring&quot;</span>
</pre></div>
</div>
<p>If you need a byte string literal under Python 2 and a unicode string literal
under Python 3, use the <a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.4)"><tt class="xref py py-class docutils literal"><span class="pre">str</span></tt></a> builtin:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">str</span><span class="p">(</span><span class="s">&#39;my string&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>In Python 3, there aren&#8217;t any automatic conversions between <tt class="docutils literal"><span class="pre">str</span></tt> and
<tt class="docutils literal"><span class="pre">bytes</span></tt>, and the <a class="reference external" href="http://docs.python.org/3/library/codecs.html#module-codecs" title="(in Python v3.4)"><tt class="xref py py-mod docutils literal"><span class="pre">codecs</span></tt></a> module became more strict. <a class="reference external" href="http://docs.python.org/3/library/stdtypes.html#str.encode" title="(in Python v3.4)"><tt class="xref py py-meth docutils literal"><span class="pre">str.encode()</span></tt></a>
always returns <tt class="docutils literal"><span class="pre">bytes</span></tt>, and <tt class="docutils literal"><span class="pre">bytes.decode</span></tt> always returns <tt class="docutils literal"><span class="pre">str</span></tt>. As a
consequence, the following pattern is sometimes necessary:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">value</span> <span class="o">=</span> <span class="n">value</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&#39;ascii&#39;</span><span class="p">,</span> <span class="s">&#39;ignore&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s">&#39;ascii&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Be cautious if you have to <a class="reference external" href="https://docs.python.org/3/howto/pyporting.html#indexing-bytes-objects">index bytestrings</a>.</p>
</div>
<div class="section" id="s-exceptions">
<span id="exceptions"></span><h4>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h4>
<p>When you capture exceptions, use the <tt class="docutils literal"><span class="pre">as</span></tt> keyword:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">try</span><span class="p">:</span>
    <span class="o">...</span>
<span class="k">except</span> <span class="n">MyException</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
    <span class="o">...</span>
</pre></div>
</div>
<p>This older syntax was removed in Python 3:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">try</span><span class="p">:</span>
    <span class="o">...</span>
<span class="k">except</span> <span class="n">MyException</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span>    <span class="c"># Don&#39;t do that!</span>
    <span class="o">...</span>
</pre></div>
</div>
<p>The syntax to reraise an exception with a different traceback also changed.
Use <a class="reference external" href="http://pythonhosted.org/six/index.html#six.reraise" title="(in six v1.9)"><tt class="xref py py-func docutils literal"><span class="pre">six.reraise()</span></tt></a>.</p>
</div>
</div>
<div class="section" id="s-magic-methods">
<span id="magic-methods"></span><h3>Magic methods<a class="headerlink" href="#magic-methods" title="Permalink to this headline">¶</a></h3>
<p>Use the patterns below to handle magic methods renamed in Python 3.</p>
<div class="section" id="s-iterators">
<span id="iterators"></span><h4>Iterators<a class="headerlink" href="#iterators" title="Permalink to this headline">¶</a></h4>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyIterator</span><span class="p">(</span><span class="n">six</span><span class="o">.</span><span class="n">Iterator</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span>             <span class="c"># implement some logic here</span>

    <span class="k">def</span> <span class="nf">__next__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">raise</span> <span class="ne">StopIteration</span>     <span class="c"># implement some logic here</span>
</pre></div>
</div>
</div>
<div class="section" id="s-boolean-evaluation">
<span id="boolean-evaluation"></span><h4>Boolean evaluation<a class="headerlink" href="#boolean-evaluation" title="Permalink to this headline">¶</a></h4>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyBoolean</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">__bool__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">True</span>             <span class="c"># implement some logic here</span>

    <span class="k">def</span> <span class="nf">__nonzero__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>      <span class="c"># Python 2 compatibility</span>
        <span class="k">return</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__bool__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-division">
<span id="division"></span><h4>Division<a class="headerlink" href="#division" title="Permalink to this headline">¶</a></h4>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyDivisible</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">__truediv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span> <span class="o">/</span> <span class="n">other</span>     <span class="c"># implement some logic here</span>

    <span class="k">def</span> <span class="nf">__div__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>   <span class="c"># Python 2 compatibility</span>
        <span class="k">return</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__truediv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">__itruediv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span> <span class="o">//</span> <span class="n">other</span>    <span class="c"># implement some logic here</span>

    <span class="k">def</span> <span class="nf">__idiv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>  <span class="c"># Python 2 compatibility</span>
        <span class="k">return</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__itruediv__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
</pre></div>
</div>
<p>Special methods are looked up on the class and not on the instance to reflect
the behavior of the Python interpreter.</p>
</div>
</div>
<div class="section" id="s-writing-compatible-code-with-six">
<span id="writing-compatible-code-with-six"></span><h3>Writing compatible code with six<a class="headerlink" href="#writing-compatible-code-with-six" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="http://pythonhosted.org/six/">six</a> is the canonical compatibility library for supporting Python 2 and 3 in
a single codebase. Read its documentation!</p>
<p>A <a class="reference internal" href="#module-django.utils.six" title="django.utils.six"><tt class="xref py py-mod docutils literal"><span class="pre">customized</span> <span class="pre">version</span> <span class="pre">of</span> <span class="pre">six</span></tt></a> is bundled with Django
as of version 1.4.2. You can import it as <tt class="docutils literal"><span class="pre">django.utils.six</span></tt>.</p>
<p>Here are the most common changes required to write compatible code.</p>
<div class="section" id="s-string-handling-with-six">
<span id="s-id1"></span><span id="string-handling-with-six"></span><span id="id1"></span><h4>String handling<a class="headerlink" href="#string-handling-with-six" title="Permalink to this headline">¶</a></h4>
<p>The <tt class="docutils literal"><span class="pre">basestring</span></tt> and <tt class="docutils literal"><span class="pre">unicode</span></tt> types were removed in Python 3, and the
meaning of <tt class="docutils literal"><span class="pre">str</span></tt> changed. To test these types, use the following idioms:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">isinstance</span><span class="p">(</span><span class="n">myvalue</span><span class="p">,</span> <span class="n">six</span><span class="o">.</span><span class="n">string_types</span><span class="p">)</span>       <span class="c"># replacement for basestring</span>
<span class="nb">isinstance</span><span class="p">(</span><span class="n">myvalue</span><span class="p">,</span> <span class="n">six</span><span class="o">.</span><span class="n">text_type</span><span class="p">)</span>          <span class="c"># replacement for unicode</span>
<span class="nb">isinstance</span><span class="p">(</span><span class="n">myvalue</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">)</span>                  <span class="c"># replacement for str</span>
</pre></div>
</div>
<p>Python ≥ 2.6 provides <tt class="docutils literal"><span class="pre">bytes</span></tt> as an alias for <tt class="docutils literal"><span class="pre">str</span></tt>, so you don&#8217;t need
<a class="reference external" href="http://pythonhosted.org/six/index.html#six.binary_type" title="(in six v1.9)"><tt class="xref py py-data docutils literal"><span class="pre">six.binary_type</span></tt></a>.</p>
</div>
<div class="section" id="s-long">
<span id="long"></span><h4><tt class="docutils literal"><span class="pre">long</span></tt><a class="headerlink" href="#long" title="Permalink to this headline">¶</a></h4>
<p>The <tt class="docutils literal"><span class="pre">long</span></tt> type no longer exists in Python 3. <tt class="docutils literal"><span class="pre">1L</span></tt> is a syntax error. Use
<a class="reference external" href="http://pythonhosted.org/six/index.html#six.integer_types" title="(in six v1.9)"><tt class="xref py py-data docutils literal"><span class="pre">six.integer_types</span></tt></a> check if a value is an integer or a long:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">isinstance</span><span class="p">(</span><span class="n">myvalue</span><span class="p">,</span> <span class="n">six</span><span class="o">.</span><span class="n">integer_types</span><span class="p">)</span>      <span class="c"># replacement for (int, long)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-xrange">
<span id="xrange"></span><h4><tt class="docutils literal"><span class="pre">xrange</span></tt><a class="headerlink" href="#xrange" title="Permalink to this headline">¶</a></h4>
<p>If you use <tt class="docutils literal"><span class="pre">xrange</span></tt> on Python 2, import <tt class="docutils literal"><span class="pre">six.moves.range</span></tt> and use that
instead. You can also import <tt class="docutils literal"><span class="pre">six.moves.xrange</span></tt> (it&#8217;s equivalent to
<tt class="docutils literal"><span class="pre">six.moves.range</span></tt>) but the first technique allows you to simply drop the
import when dropping support for Python 2.</p>
</div>
<div class="section" id="s-moved-modules">
<span id="moved-modules"></span><h4>Moved modules<a class="headerlink" href="#moved-modules" title="Permalink to this headline">¶</a></h4>
<p>Some modules were renamed in Python 3. The <tt class="docutils literal"><span class="pre">django.utils.six.moves</span></tt>
module (based on the <a class="reference external" href="http://pythonhosted.org/six/index.html#module-six.moves" title="(in six v1.9)"><tt class="xref py py-mod docutils literal"><span class="pre">six.moves</span> <span class="pre">module</span></tt></a>) provides a
compatible location to import them.</p>
</div>
<div class="section" id="s-py2">
<span id="py2"></span><h4>PY2<a class="headerlink" href="#py2" title="Permalink to this headline">¶</a></h4>
<p>If you need different code in Python 2 and Python 3, check <a class="reference external" href="http://pythonhosted.org/six/index.html#six.PY2" title="(in six v1.9)"><tt class="xref py py-data docutils literal"><span class="pre">six.PY2</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre>if six.PY2:
    # compatibility code for Python 2
</pre></div>
</div>
<p>This is a last resort solution when <a class="reference external" href="http://pythonhosted.org/six/index.html#module-six" title="(in six v1.9)"><tt class="xref py py-mod docutils literal"><span class="pre">six</span></tt></a> doesn&#8217;t provide an appropriate
function.</p>
<span class="target" id="module-django.utils.six"></span></div>
</div>
<div class="section" id="s-django-customized-version-of-six">
<span id="django-customized-version-of-six"></span><h3>Django customized version of six<a class="headerlink" href="#django-customized-version-of-six" title="Permalink to this headline">¶</a></h3>
<p>The version of six bundled with Django (<tt class="docutils literal"><span class="pre">django.utils.six</span></tt>) includes a few
customizations for internal use only.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Porting to Python 3</a><ul>
<li><a class="reference internal" href="#philosophy">Philosophy</a></li>
<li><a class="reference internal" href="#porting-tips">Porting tips</a><ul>
<li><a class="reference internal" href="#unicode-literals">Unicode literals</a></li>
<li><a class="reference internal" href="#string-handling">String handling</a></li>
<li><a class="reference internal" href="#str-and-unicode-methods"><tt class="docutils literal"><span class="pre">__str__()</span></tt> and &nbsp;__unicode__() methods</a></li>
<li><a class="reference internal" href="#dict-and-dict-like-classes"><tt class="docutils literal"><span class="pre">dict</span></tt> and <tt class="docutils literal"><span class="pre">dict</span></tt>-like classes</a></li>
<li><a class="reference internal" href="#httprequest-and-httpresponse-objects"><tt class="docutils literal"><span class="pre">HttpRequest</span></tt> and <tt class="docutils literal"><span class="pre">HttpResponse</span></tt> objects</a></li>
</ul>
</li>
<li><a class="reference internal" href="#coding-guidelines">Coding guidelines</a><ul>
<li><a class="reference internal" href="#syntax-requirements">Syntax requirements</a><ul>
<li><a class="reference internal" href="#unicode">Unicode</a></li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#magic-methods">Magic methods</a><ul>
<li><a class="reference internal" href="#iterators">Iterators</a></li>
<li><a class="reference internal" href="#boolean-evaluation">Boolean evaluation</a></li>
<li><a class="reference internal" href="#division">Division</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-compatible-code-with-six">Writing compatible code with six</a><ul>
<li><a class="reference internal" href="#string-handling-with-six">String handling</a></li>
<li><a class="reference internal" href="#long"><tt class="docutils literal"><span class="pre">long</span></tt></a></li>
<li><a class="reference internal" href="#xrange"><tt class="docutils literal"><span class="pre">xrange</span></tt></a></li>
<li><a class="reference internal" href="#moved-modules">Moved modules</a></li>
<li><a class="reference internal" href="#py2">PY2</a></li>
</ul>
</li>
<li><a class="reference internal" href="#django-customized-version-of-six">Django customized version of six</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h3>Browse</h3>
  <ul>
    
      <li>Prev: <a href="pagination.html">Pagination</a></li>
    
    
      <li>Next: <a href="security.html">Security in Django</a></li>
    
  </ul>
  <h3>You are here:</h3>
  <ul>
      <li>
        <a href="../index.html">Django 1.7.8.dev20150401230226 documentation</a>
        
          <ul><li><a href="index.html">Using Django</a>
        
        <ul><li>Porting to Python 3</li></ul>
        </li></ul>
      </li>
  </ul>

  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="../_sources/topics/python3.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Apr 02, 2015</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="pagination.html" title="Pagination">previous</a>
     |
    <a href="index.html" title="Using Django" accesskey="U">up</a>
   |
    <a href="security.html" title="Security in Django">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>